Skip to content

Make social icon configuration more flexible #3025

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 16 commits into from
Apr 7, 2025
Merged

Make social icon configuration more flexible #3025

merged 16 commits into from
Apr 7, 2025
+137 −175

Conversation

@delucis
Copy link
Member

@delucis delucis commented Mar 26, 2025 •
edited
Loading

Description

  • This PR changes how social links are configured in the Starlight options.

  • It switches from a shorthand object syntax to an array of explicit link items:

    - social: {
-   github: 'https://github.com/withastro/starlight',
-   discord: 'https://astro.build/chat',
- },
+ social: [
+   { icon: 'github', label: 'GitHub', href: 'https://github.com/withastro/starlight' },
+   { icon: 'discord', label: 'Discord', href: 'https://astro.build/chat' },
+ ],

  • This is a little unfortunate in that it’s a more verbose configuration approach, but it has a few advantages for long-term maintenance:

    • Icons no longer need dedicated built-in labels and code to be used as social links. Any icon can be used if people want (avoiding us needing to decide what counts as a valid social link and what doesn’t).

    • User control of labels means that less common links can be labelled accurately. For example, we avoided adding an email social icon because the label could vary depending on site language and context. This change allows people to use the existing email icon with a label of their choosing.

    • Following Add support for custom icons #3024, this should be updated to also support user-installed icons reducing the pressure on Starlight to contain icons for every platform in the known universe.

Not in scope

  • Currently there’s no implementation of localized labels for social links in this PR. There are a few obstacles to implementing that nicely at the moment, and given labels are already not localizable (and for many cases don’t require it where the label is a platform name), we decided to skip that until we refactor some internals to make it easier to support that elegantly.

Also considered

  • I also considered whether some hybrid of our current shorthand syntax and the new explicit syntax could make sense to keep config for common platforms terse, but I decided the slightly less verbose syntax didn’t justify users needing to understand two subtly different link shapes (e.g. some icons not needing an explicit label).

@changeset-bot
Copy link

changeset-bot bot commented Mar 26, 2025 •
edited
Loading

🦋 Changeset detected

Latest commit: bd5f90f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
@astrojs/starlight Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@github-actions github-actions bot added 📚 docs Documentation website changes 🌟 core Changes to Starlight’s main package labels Mar 26, 2025
@astrobot-houston
Copy link
Contributor

astrobot-houston commented Mar 26, 2025 •
edited
Loading

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

Locale File Note
en guides/customization.mdx Source changed, localizations will be marked as outdated.
en reference/configuration.mdx Source changed, localizations will be marked as outdated.
en reference/plugins.md Source changed, localizations will be marked as outdated.
Warnings reference
Icon Description
🔄️ The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

@netlify
Copy link

netlify bot commented Mar 26, 2025 •
edited
Loading

✅ Deploy Preview for astro-starlight ready!

Name Link
🔨 Latest commit bd5f90f
🔍 Latest deploy log https://app.netlify.com/sites/astro-starlight/deploys/67f3ef1b8fe7e80008d08f4f
😎 Deploy Preview https://deploy-preview-3025--astro-starlight.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
Lighthouse
Lighthouse		 1 paths audited
Performance: 100 (no change from production)
Accessibility: 100 (no change from production)
Best Practices: 100 (no change from production)
SEO: 92 (no change from production)
PWA: -
View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify site configuration.

@astrobot-houston
Copy link
Contributor

astrobot-houston commented Mar 26, 2025 •
edited
Loading

size-limit report 📦

Path Size
/index.html 6.93 KB (0%)
/_astro/*.js 25.76 KB (0%)
/_astro/*.css 13.86 KB (0%)

@delucis delucis added the 🌟 minor Change that triggers a minor release label Mar 26, 2025
delucis
delucis commented Mar 26, 2025
View reviewed changes
packages/starlight/components/Head.astro Outdated
Comment on lines 86 to 96
// Link to Twitter account if set in Starlight config.
if (config.social?.twitter) {
const twitterLink = config.social?.find(({ icon }) => icon === 'twitter' || icon === 'x.com');
if (twitterLink) {
headDefaults.push({
tag: 'meta',
attrs: {
name: 'twitter:site',
content: new URL(config.social.twitter.url).pathname,
content: new URL(twitterLink.href).pathname,
},
});
}
Copy link
Member Author

@delucis delucis Mar 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This change will overlap with #2927 but thankfully it’s small and easy to update for whichever PR merges second.

HiDeoo
HiDeoo approved these changes Apr 1, 2025
View reviewed changes
Copy link
Member

@HiDeoo HiDeoo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks amazing and definitely more flexible for users 👏

Left a few link suggestions and thoughts but nothing blocking 👍

@delucis delucis added this to the v0.33 milestone Apr 5, 2025
@delucis delucis added the ✅ approved Pull requests that have been approved and are ready to merge when next cutting a release label Apr 5, 2025
@delucis delucis mentioned this pull request Apr 7, 2025
Closed
@github-actions github-actions bot added the i18n Anything to do with internationalization & translation efforts label Apr 7, 2025
@delucis delucis merged commit f87e9ac into main Apr 7, 2025
16 checks passed
@delucis delucis deleted the chris/social-links branch April 7, 2025 15:33
@astrobot-houston astrobot-houston mentioned this pull request Apr 7, 2025
Merged
This was referenced Apr 7, 2025
Merged
Merged
Merged
Merged
This was referenced Apr 8, 2025
Merged
Merged
Merged
This was referenced Apr 10, 2025
Merged
Merged
Merged
This was referenced Apr 13, 2025
Merged
Merged
Merged
@stephenh stephenh mentioned this pull request Apr 25, 2025
Closed
@yashuatla yashuatla mentioned this pull request Jun 24, 2025
Open
Yoxnear pushed a commit to Yoxnear/starlight-custom that referenced this pull request Jul 23, 2025
@delucis @HiDeoo
Make social icon configuration more flexible (withastro#3025)
126c0d3 
Co-authored-by: HiDeoo <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@HiDeoo HiDeoo HiDeoo approved these changes

Assignees

No one assigned

Labels

✅ approved Pull requests that have been approved and are ready to merge when next cutting a release 🌟 core Changes to Starlight’s main package 📚 docs Documentation website changes i18n Anything to do with internationalization & translation efforts 🌟 minor Change that triggers a minor release

Projects

None yet

Milestone

v0.33

Development

Successfully merging this pull request may close these issues.

4 participants

@delucis @astrobot-houston @HiDeoo